home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 November: Tool Chest / Dev.CD Nov 98 TC.toast / Sample Code / Devices / AsyncDriverSample1.0b4 / TradDriverLoaderLib / TradDriverLoaderLib.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-05-21  |  10.1 KB  |  217 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        TradDriverLoaderLib.h
  3.  
  4.     Contains:    C interface for the pseudo-DriverLoaderLib for 'DRVR's.
  5.  
  6.     Written by:    Quinn "The Eskimo!"
  7.  
  8.     Copyright:    © 1996 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.     You may incorporate this sample code into your applications without
  13.     restriction, though the sample code has been provided "AS IS" and the
  14.     responsibility for its operation is 100% yours.  However, what you are
  15.     not permitted to do is to redistribute the source as "DSC Sample Code"
  16.     after having made changes. If you're going to re-distribute the source,
  17.     we require that you make it clear in the source that the code was
  18.     descended from Apple Sample Code, but that you've made changes.
  19. */
  20.  
  21. #include <Types.h>
  22. #include <Devices.h>
  23.  
  24. #ifdef __cplusplus
  25. extern "C" {
  26. #endif
  27.  
  28. ///////////////////////////////////////////////////////////////////////////
  29.  
  30. // The following routines are implemented with semantics virtually identical
  31. //  to those found in DriverLoaderLib.  You should look in
  32. //  "Designing PCI Cards and Drivers for Power Macintosh Computers" for
  33. //  documentation.  You can FTP an electronic copy from:
  34. /*  <ftp://ftpdev.info.apple.com//Developer_Services/
  35.      Technical_Documentation/PCI_Information/Designing_PCI_Cards_-_Driv.sit.>
  36. */
  37.  
  38. extern pascal SInt16 TradHigherDriverVersion(NumVersion *dv1, NumVersion *dv2);
  39.  
  40. extern pascal UnitNumber TradHighestUnitNumber(void);
  41.  
  42. extern pascal OSErr TradDriverGestaltOn(DriverRefNum refNum);
  43.  
  44. extern pascal OSErr TradDriverGestaltOff(DriverRefNum refNum);
  45.  
  46. extern pascal Boolean TradDriverGestaltIsOn(DriverFlags flags);
  47.  
  48. extern pascal OSErr TradLookupDrivers(UnitNumber beginningUnit,
  49.                                         UnitNumber endingUnit,
  50.                                         Boolean emptyUnits,
  51.                                         ItemCount *returnedRefNums, 
  52.                                         DriverRefNum *refNums);
  53.  
  54. ///////////////////////////////////////////////////////////////////////////
  55.  
  56. // The following routines are similar to the corresponding routines in
  57. //  DriverLoaderLib, but their interface differs because of the
  58. //  inherent differences between 'DRVR's and 'ndrv's.  The comments
  59. //  cover the differences for each routine.  If there's a difference
  60. //  that's not commented, it's most probably a bug and you should let
  61. //  me know.
  62.  
  63. extern pascal OSErr TradInstallDriverFromPtr(DRVRHeaderPtr driver,
  64.                                                 UnitNumber beginningUnit,
  65.                                                 UnitNumber endingUnit,
  66.                                                 DriverRefNum *refNum);
  67.     // This routine is similar to InstallDriverFromMemory except
  68.     //  that you pass a pointer to the 'DRVR', rather than a base pointer
  69.     //  and length.  This pointer is copied verbatim into the dCtlDriver
  70.     //  field of the DCE, so you have to make sure that it's in
  71.     //  the system heap if the driver is going to hang around longer than
  72.     //  your application.
  73.     // One other deviation from InstallDriverFromMemory is that this
  74.     //  call won't replace an existing driver.  This is because 'DRVR's
  75.     //  don't have infrastructure to support this.  If there's already
  76.     //  a driver of the same name in the unit table, the call will fail
  77.     //  with a dupFNErr, and *refNum will be set to the refnum of the
  78.     //  existing driver.
  79.     // The semantics of the endingUnit match those of DriverLoaderLib,
  80.     //  ie the call will not grow the unit table unless endingUnit is
  81.     //  greater than TradHighestUnitNumber.  The simplest way to work
  82.     //  this is to pass TradHighestUnitNumber() + 1 to endingUnit.
  83.     // If the call fails, it's your responsibility to dispose of the
  84.     //  the driver pointer.  If it succeeds, the system has a copy
  85.     //  of the pointer, which can be disposed by calling TradRemoveDriver.
  86.  
  87. extern pascal OSErr TradInstallDriverFromHandle(DRVRHeaderHandle driver,
  88.                                                 UnitNumber beginningUnit,
  89.                                                 UnitNumber endingUnit,
  90.                                                 DriverRefNum *refNum);
  91.     // This routine is similar to InstallDriverFromMemory except
  92.     //  that you pass a handle to the 'DRVR', rather than a base pointer
  93.     //  and length.  This is generally more convenient in the traditional
  94.     //  'DRVR' world.
  95.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  96.     //  The routine simply creates a pointer in the system heap and copies
  97.     //  your driver into it, then calls TradInstallDriverFromPtr.  Because
  98.     //  a copy is made, you do not have to ensure that the handle you
  99.     //  pass in is in the system heap.
  100.     // Regardless of whether call succeeds or fails, it's your responsibility
  101.     //  to dispose of the driver handle.
  102.     
  103. extern pascal OSErr TradInstallDriverFromResource(SInt16 rsrcID, StringPtr rsrcName,
  104.                                                 UnitNumber beginningUnit,
  105.                                                 UnitNumber endingUnit,
  106.                                                 DriverRefNum *refNum);
  107.     // This call offers functionality like InstallDriverFromFile.
  108.     //  It differs from InstallDriverFromFile in that the driver is expected
  109.     //  to be in a resource in the current resource file.  If rsrcName is nil,
  110.     //  the call uses Get1Resource('DRVR', rsrcID) to get the driver.  If
  111.     //  rsrcName is not nil, it uses Get1NamedResource('DRVR', rsrcName)
  112.     //  to get the driver.
  113.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  114.     // If the call fails, the routine will clean up after itself.  If the
  115.     //  call succeeds, the driver code is left as a memory block in the system
  116.     //  heap, which can be cleaned up by calling TradRemoveDriver.
  117.  
  118. extern pascal OSErr TradGetDriverInformation(DriverRefNum refNum,
  119.                                                 UnitNumber *thisUnit,
  120.                                                 DriverFlags *flags,
  121.                                                 StringPtr name,
  122.                                                 DRVRHeaderPtr *driverHeader
  123.                                                 );
  124.     // This routine is like GetDriverInformation except that it only
  125.     //  returns information that's pertinant to the traditional 'DRVR'
  126.     //  world.  driverHeader comes back as a pointer to the beginning
  127.     //  of the 'DRVR' header.
  128.     // Note that this routine works for both drivers installed by
  129.     //  this library and other drivers, however for drivers not installed
  130.     //  by this library (ie 'RAM'-based drivers), driverHeader may be a 
  131.     //  half dereferenced handle, locked or unlocked.  You have been warned.
  132.     // Also, driverHeader can come back set to nil, if the driver
  133.     //  is installed but its code has been purged, for example a DA.
  134.     //  You must check for this before deferencing it.  If driverHeader
  135.     //  is set to nil, name will be set to the empty string.
  136.  
  137. extern pascal OSErr TradOpenInstalledDriver(DriverRefNum refNum, SInt8 ioPermission);
  138.     // This routine has the same semantics as OpenInstalledDriver
  139.     //  except that the ioPermission parameter must be fsRdWrPerm.  This is
  140.     //  because we call through to the Device Manager's OpenDriver routine,
  141.     //  and that doesn't support passing in permissions.  I could switch the
  142.     //  implementation to use PBOpen, but PBOpen is a trap fraught with much
  143.     //  danger, so I'm avoiding it at the moment.
  144.     // The danger associated with PBOpen is that it's highly overloaded,
  145.     //  being used for FSOpen, PBOpen, PBHOpen, OpenSlot, OpenDriver,
  146.     //  OpenDeskAcc, and so on.  If you get the glue wrong, you die in
  147.     //  strange and evil ways.  So I'm bypassing the entire problem by
  148.     //  ignoring ioPermission.  I may revisit this decision, but not soon.
  149.  
  150. extern pascal OSErr TradRemoveDriver(DriverRefNum refNum, Boolean immediate);
  151.     // This routine implements similar semantics to RemoveDriver, except
  152.     //  that the Immediate parameter must be false.  This is because
  153.     //  we close the driver using PBCloseSync, which is a queued
  154.     //  command, just like all the others.  We have no way to bypass
  155.     //  this.
  156.     // An important thing to note is that you should only call this on drivers
  157.     //  you installed using this library's TradInstallDriverFromHandle
  158.     //  and TradInstallDriverFromResource routine.  Don't call it on
  159.     //  drivers installed by other people and be careful when calling it on
  160.     //  drivers installed using TradInstallDriverFromPtr because you might
  161.     //  be disposing the driver code even though a) it might not actually be a
  162.     //  Memory Manager pointer block, or b) it might be still in use
  163.     //  by another driver.
  164.  
  165. extern pascal OSErr TradRenameDriver(DriverRefNum refNum, ConstStr255Param newDriverName);
  166.     // This routine is implemented with the caveat that you can't
  167.     //  make the driver name longer.  This is because the 'DRVR'
  168.     //  name is actually stored in the code resource which implements
  169.     //  the driver, and making it longer would cause it to run into
  170.     //  the code that immediately follows the name.
  171.     // The reason why I implemented this routine at all is because
  172.     //  it's useful for installing multiple copies of the same driver.
  173.     //  For example, you can install ".Q_Out", then rename it to
  174.     //  ".QAOut", and then install ".Q_Out" again, and rename that to
  175.     //  ".QBOut".  This can be very useful when testing and debugging
  176.     //  your driver (or TradDriverLoaderLib for that matter :).
  177.     // You should take extreme care when calling this routine on drivers that
  178.     //  weren't installed with this library.  Some of these drivers might
  179.     //  not like being renamed in this way.
  180.  
  181. ///////////////////////////////////////////////////////////////////////////
  182.  
  183. // The following routines from DriverLoaderLib were not implemented because
  184. //  they make no sense at all in the world of 'DRVR's.
  185.  
  186. // VerifyFragmentAsDriver
  187. // GetDriverMemoryFragment
  188. // GetDriverDiskFragment
  189. // InstallDriverFromFragment
  190. // SetDriverClosureMemory
  191. // -- If they've got fragment in the name, it's hard to map them into the
  192. // 'DRVR' world.  Traditional 'DRVR's just aren't code fragments!
  193.  
  194. // InstallDriverFromFile -- This routine assumes that there's only
  195. //    one driver in a file, which is not the case for traditional 'DRVR's
  196. //  which are normally stored as resources.  The basic functionality has
  197. //  been subsumed by TradInstallDriverFromResource.
  198.  
  199. // InstallDriverFromDisk
  200. // FindDriversForDevice
  201. // FindDriverCandidates
  202. // ScanDriverCandidates
  203. // GetDriverForDevice
  204. // InstallDriverForDevice
  205. // -- These routines all assume that there's some magic way of matching
  206. //  drivers to their name register nodes.  In the traditional world, there
  207. //  is no name registry and, even if there was, there's no way to match
  208. //  devices against hardware.  So these routines are not sensible in the
  209. //  traditional world. 
  210.  
  211. // ReplaceDriverWithFragment -- There's no good way to replace a traditional
  212. //  device driver; the infrastructure just isn't there.
  213.  
  214. #ifdef __cplusplus
  215. }
  216. #endif
  217.